<html>
<head>
<title>Installing and Configuring OGR WCTS</title>
</head>

<body>

<h1>Installing and Configuring OGR WCTS</h1>

The OGR WCTS server is currently implemented as a C++ cgi-bin style web
service.  It should be useable with any web server that supports passing
on arguments via QUERY_STRING and posted input via stdin.<p>

<h2>Build and Install PROJ.4</h2>

The OGR WCTS server depends on PROJ.4 for doing the actual transformations.
It is therefore necessary to build and install PROJ.4, preferrably before
building and installing GDAL.  Download the latest source release from
<a href="http://www.remotesensing.org/proj">http://www.remotesensing.org/proj
</a>.  Ensure you get PROJ 4.4.7 or later if NTv2 datum shifting support
is required.<p>

If US grid based NAD27 datum shifting is required for North America, it is
imperative to unpack the the datum shift files "on" the PROJ.4 source
tree before configuring, building and installing.<p>

<pre>
% tar xzvf proj-4.4.7.tar.gz
% cd proj-4.4.7/nad
% tar xzvf ../../proj-nad27-1.1.tar.gz
% cd ..
% ./configure
% make
% su
Password: *******
$ make install
$ exit
</pre>

If NTv2 support is desired, download the NTv2 data file from the
<a href="http://www.geod.emr.ca/index_e/products_e/software_e/ntv2_e.html">
Natural Resources Canada</a> web site, and copy it to 
/usr/local/share/proj.  This can be safely done after PROJ.4 is installed.
The file is platform independent (unlike the binary files built for
the US grid shift files).  Please ensure the file is installed with the
filename in lower case.<p>

<pre>
$ cp NTV2_0.GSB /usr/local/share/proj/ntv2_0.gsb
</pre>

<h2>Build and Install GDAL</h2>

Currently a build mechanism only exists for Unix, and the WCTS server is
not built and installed as a standard part of GDAL/OGR.  However it does
<i>live</i> in the GDAL/OGR source tree in the ogr/wcts directory.  The
source (such as a nightly CVS snapshot) can be downloaded from the 
<a href="http://www.remotesensing.org/gdal">GDAL/OGR web site</a>.<P>

Once unpacked, build GDAL/OGR according to the <a href=
"http://www.remotesensing.org/gdal/gdal_building.html">provided 
instructions</a>, and then install.<P>

<pre>
% cd gdal
% ./configure
...
% make
% su 
Password: ********
$ make install
$ exit
</pre>

<h2>Build and Install OGR WCTS Server</h2>

Next, build the WCTS server itself.  It is found in ogr/wcts.
If you wish the ability to fetch remote GML files, ensure that 
<a href="http://curl.haxx.se/libcurl/c">libcurl</a> is installed, and
uncomment the CURL_LIB and CURL_DEF lines in the GNUmakefile.  Ensure
that the CURL_LIB is defined appropriately to find libcurl on your system.<p>
Then build the server.<p>

<pre>
% cd ogr/wcts
% make 
</pre>

The server (ogrwcts) is a simple executable that depends on libgdal.1.1, and
potentially on libcurl.  It would normally be copied directly into your
web server cgi-bin directory.<p>

<pre>
% cp ogrwcts /u/apache/cgi-bin
</pre>

If you want the HTML form based WCTS client (demonstrated at
<a href="http://maps.gdal.org/wcts/client.html">
http://maps.gdal.org/wcts/client.html</a> to have a local cgi-bin 
server, you should also build the <b>wctsclient</b> application.<p>

<pre>
% make all
% cp wctsclient /u/apache/cgi-bin
</pre>

<h2>GetCapabilities</h2>

The server needs to be able to respond to a <b>GetCapabilities</b> request. 
The response document is actually created statically ahead of time.  There
is a provided sample in the ogr/wcts directory called 
wcts_capabilities.xml.0.1.0.  It should generally be updated depending on
the nature of the service being setup.  In particular, the ContactInformation
should be updated to refer to whoever is setting up the service.  Also, all
the service URLs all need to be updated to reflect the url for the service
as it is being installed.  Change each occurance of 
"http://maps.gdal.org/cgi-bin/ogrwcts?to the appropriate value. <p>

<pre>
% vi wcts_capabilities.xml.0.1.0
% cp wcts_capabilities.xml.0.1.0 /usr/local/share/gdal
</pre>

Next this modified document (with the name unchanged) needs to be placed some
where it can be found by the server.  The ideal location is the 
/usr/local/share/gdal directory since it is already in the "data file search
path".  If it is placed elsewhere, the -data switch to ogrwcts will need to 
be used to point to the directory.  Note, all aspects of the server other
than the <b>GetCapabilities</b> request will work fine even without the
capabilities document.<p>

<h2>Commandline Testing of Server</h2>

Before trying under the web server, it may be helpful to test the WCTS
server as a commandline program.  Some sample requests are available in
the wcts build directory, and can be used like this:

<pre>
% cd ogr/wcts
% ./ogrwcts -put < req_getcap.xml
% ./ogrwcts -put < req_istransformable.xml
% ./ogrwcts -put < req_transform.xml
</pre>

<h2>Web Server Setup</h2>

It is assumed that the web server is already setup to allow cgi-bin
programs to be executed in the directory you installed the ogrwcts executable.
If not, correct this.<P>

It is also necessary for the ogrwcts program to be able to load the shared
libraries it depends on.  In a default install under /usr/local, this might
involved adding the directive "SetEnv LD_LIBRARY_PATH /usr/local/lib" in 
an Apache configuration file, or utilizing ldconfig to ensure that 
libgdal.1.1.so, and libproj.so will be found when ogrwcts is started.<p>

It is also necessary that directories with the supporting data files
used by ogrwcts be readable by the user that cgi-bin programs run as
(often "nobody").  In a default install the directories in question are
/usr/local/share/gdal and /usr/local/share/proj.   Usually these locations
will be world readable by default.<p>

<h2>Debugging</h2>

If the server isn't working there are a few strategies to debugging problems.
<P>

<ol>
<li> Most errors will result in an XML exception document being returned. 
If so, it should contain some indication of what went wrong.<p>
<li> Ensure that ogrwcts works standalone (see Commandline Testing of Server
above). 
<li> Check the error log for the web server and check for messages there.
Common problems would be web server permissions problems for the cgi-bin or
failure to load the shared libraries. <p>
<li> Run the server with full debugging turned on.  This can be accomplished
by passing the <b>-debug</b> commandline switch.  This will various debugging
information from GDAL/OGR, and PROJ.4 to be logged in the error file, 
including details of what grids are being used for datum shifting.<P>
</ol>

If all the above have been exausted, bugs with OGR WCTS 
<a href="http://bugzilla.remotesensing.org/enter_bug.cgi?product=GDAL&component=OGR_SRS">may be reported</a> via the GDAL/OGR Bugzilla.<p>

<h2>Installing in Non-Default Locations</h2>

It is often desirable to install GDAL, and PROJ.4 in a non-default location
in order to better control software configurations.  This can be accomplished
by using the <i>--prefix</i> flag when configuring them. For example:<p>

<pre>
% ./configure --prefix=/opt
</pre>

This mechanism can be used while configuring both GDAL and PROJ.4 (and
presumably libcurl).  Appropriate adjustements to the LD_LIBRARY_PATH or
ldconfig settings would be required to find support libraries in 
${prefix}/lib.  Default path to files supporting GDAL, and PROJ.4 are 
established during their builds (based on the configure --prefix setting), 
so these components should be able to find their supporting data files as
long as everything is built and installed consistently.<p>

Sometimes it is also desirable to force the <b>ogrwcts</b> cgi-bin to use
particular versions of local files.  This is normally accomplished by
using a shell script as the target cgi-bin, and having that script run
ogrwcts with appropriate override commandline switches and environment 
variables.<p>

The <b>PROJ_LIB</b> environment variable can be set to point to an alternate
location to find supporting datum shift files for PROJ.4.  They are
normally kept in /usr/local/share/proj.<p>

The <b>GDAL_DATA</b> environment variable may be used to set an alternate
source for the .csv files used to translate EPSG CRS numbers into 
detailed definitions.   They are normally kept in /usr/local/share/gdal.<p>

The <b>-data</b> <i>directory</i> commandline switch to <b>ogrwcts</b> may
be used to designate an alternate search directory for GDAL .csv files, and
the capabilities document.<p>

This is an example of a script that might be to override selected environment 
variables before running the real ogrwcts binary.<p>

<pre>
#! /bin/sh

LD_LIBRARY_PATH=/home/warmerda/gdal:/usr/local/lib
export LD_LIBRARY_PATH
PROJ_LIB=/usr2/cgi-bin/wcts-proj-lib
export PROJ_LIB
/home/warmerda/gdal/ogr/wcts/ogrwcts $*
exit 0
</pre>

</body>
</html>
